SPEC-PWF · v0.11
28 June 2026
Owner: Platform team

Process workflows — master map

The behavioural reading of the platform: the business processes that run across the six apps, drawn as swimlanes over the model the other three document sets define. Where the PRD says what must be true, the ERD says how it is stored and the Domain set says which service owns it, this set says in what order it happens, who acts, and which event carries each hand-off.

1The workflow document set

Fourteen logical processes, one per document, so no single page carries the whole platform. Each drill-down holds one swimlane, its step table, the events it rides and its cross-references back into the spec.

As the set grew past a single flat list, related processes were gathered into sub-hierarchies — each a folder with its own overview manual. Onboarding (SPEC-PWF-ONB) groups the customer & partner front doors and capability & enrollment under workflow/onboard/; Federation (SPEC-PWF-FED) groups sign-in, access, roles and permissions under workflow/federation/ — the four processes of the PRD's six-layer identity model; Service operations (SPEC-PWF-OPS) groups the coverage, incident, field-visit and billing lifecycles under workflow/operate/. The doc-nav shows a group as one entry until you step inside it, then it expands to its members. Quote-to-cash and partner channel remain standalone for now (candidate next group: sell & channel).

2The process landscape

The fourteen workflows arranged by lifecycle phase. Establish brings a customer or partner onto the platform, lets a tenant gain a second capability, and governs who may do what; Sell & provision turns demand into commissioned devices through the channel and the won-deal saga; Operate is the ongoing loop — the agreement renews per device, incidents resolve, engineers execute on-site visits, invoices settle. Click any tile to open its workflow.

3Actors & lanes

Every swimlane is built from this shared cast, so a lane means the same thing in every workflow. Lanes are authorization, not decoration (WF-4): a step sits in the lane of the actor entitled to perform it.

4Which workflow touches which app

The surfaces each process appears on. A workflow rarely lives in one app — customer onboarding spans Account and Admin, partner onboarding adds Partners, quote-to-cash spans Pipeline, Admin and Account — which is exactly why the shell is federated.

5Reading a workflow

Each drill-down opens with one vertical swimlane: lanes are columns (the actors), and steps flow top to bottom in sequence. Node shape carries meaning — the same idiom on every diagram:

• Start / outcome are pills — every workflow names exactly one trigger and at least one terminal outcome (WF-1). No open-ended flows.
• Actions are an actor doing something on a surface; the lane's colour bar marks who. A mono caption under an action names the domain event it emits.
• Backbone events are grey nodes carrying a mono aggregate.fact key — the hand-off from one service to another rides the event backbone, never a hidden synchronous call (WF-3).
• Decisions are diamonds; every branch carries a labelled condition and a defined target (WF-6). Loop-backs (a renewal returning to the active agreement, a resend) route through the right-hand gutter as dashed edges.

The step table below each swimlane carries the detail, the emitted event and the requirement IDs each step traces to; the cross-reference block links every id, event, service and entity back to the document that owns it.

6Workflow governance rules

The WF-rules — the conditions that keep a workflow honest as a view over the spec. Defined once in the central catalog; each drill-down repeats the subset that binds it. They extend, never restate, the DM-rules (ERD) and SVC-rules (Domain).

7Traceability & open questions

Each workflow traces to the requirements it realizes and the events it rides; no step stands without evidence (WF-2). Gaps below carry the same ⚠ flags as the master ERD and domain set — a workflow exposes them as lived process pain, it does not close them.

Workflow	Realizes	Rides events
Customer onboarding	TEN-1 · TEN-4 ⚠ · ID-3 · ACC-1 · ACC-5 · ADM-1 · ADM-2	tenant.self-registered · tenant.provisioned · user.invited · user.email-verified
Partner onboarding	TEN-1 · PAR-7 ⚠ · PRT-9 · FED-8 ⚠ · AUTH-2 · ACC-5	tenant.self-registered · tenant.provisioned · user.email-verified · partner.approved
Capability & enrollment	TEN-2 · TEN-5 ⚠ · PAR-7 ⚠ · PRT-9 · PTL-1	partner.approved · tenant.capability-enabled
Sign-in & session	ID-1…3 · AUTH-1 · AUTH-2 · ACC-5 · ADM-5	— (sessions are runtime, ID-4)
Users, roles & partner access	ACC-2 · AUTH-1 · AUTH-4 · PRT-1 · PRT-3 · PRT-5	user.invited · user.role-changed · partner-link.lapsed
Defining roles	FED-6 · FED-7 · FED-8 ⚠ · AUTH-1	— (role-set edits are internal)
Permission matrix & scope	FED-9 · FED-10 · AUTH-3 · ACC-2	— (matrix edits are internal)
Sales	PIP-1…3 · ADM-2 · ACC-3	deal.won · device.commissioned · agreement.attached · invoice.issued
Partner channel	PAR-6 · PRT-9…12	deal.registered · deal.channel-changed · distribution-agreement.registered
Maintenance lifecycle	PRT-1 · PRT-2 · PRT-8	agreement.attached · .expiring · .renewed · .moved · partner-link.lapsed
Incident response	PTL-1 · PTL-2 · PTL-4 · PTL-5	alert.raised · .acknowledged · ticket.created · visit.scheduled · device.command-executed
Field visit	FLD-1…9 · DM-27…31	visit.scheduled · visit.checked-in · visit.completed · maintenance.due
Invoice lifecycle	ACC-3 · ADM-3	invoice.issued · invoice.overdue

• ⚠ TEN-4 / PAR-7 / TEN-5 / FED-8 — owner-led onboarding is not yet in the model. Splitting onboarding into a customer and a partner front door (plus capability & enrollment) introduces four proposed requirements: self-registration (TEN-4), partner self-application & program approval (PAR-7), post-onboarding capability change on the same tenant (TEN-5), and an explicit partner Owner role (FED-8). None exist in the master PRD yet — to be added with traceability rows and ERD entities in the next cascade. Until then these steps are flagged, not silent.
• ⚠ ACC-6 — no notifications consumer. Onboarding's owner invite and billing's overdue dunning both emit a fact (user.invited, invoice.overdue) with no delivery step — the same gap the domain set flags. Each workflow marks the step rather than inventing a channel.
• ⚠ ID-4 — sessions are runtime by design. Sign-in produces no persisted entity; the workflow ends at "session active" and the token is the artefact.
• ⚠ PTL-1 — the telemetry plane is upstream of the model. Incident response begins at alert.raised; threshold evaluation lives outside Postgres and is not a workflow step here.
• Quote acceptance is RiverSync-recorded — there is no customer-facing acceptance step in quote-to-cash yet (mirrors the domain open question).
• New requirements pending cascade. The onboarding split is the first workflow change to outrun the PRD/ERD; the four proposed ids above are logged here per the alignment rule (add the requirement + traceability row, or log it) and will be reconciled into the master PRD and ERD before this set leaves draft.

8Revision history

Version	Date	Changes
0.1	13 Jun 2026	First draft — the process-workflow set joins the documentation tree (SPEC-PWF + eight drill-downs). Central catalog (workflow-catalog.js: 9 actors, 8 workflows, WF-1…8), the vertical-swimlane renderer, the process landscape, actor/lane model, workflow×app matrix, traceability. Doc-nav gains the Process workflows family and curated cross-system related links.
0.2	13 Jun 2026	Onboarding split into Customer onboarding (SPEC-PWF-CON) and Partner onboarding (SPEC-PWF-PON), with a new Capability & enrollment drill-down (SPEC-PWF-ENR) for post-onboarding upgrades — now 10 workflows. Adds owner-led self-registration as a second entry path, the partner-program approval gate (subtype RiverSync-set, PRT-9), and the same-tenant capability model (TEN-2). Four proposed requirements logged for the PRD/ERD cascade (TEN-4, PAR-7, TEN-5, FED-8); new events tenant.self-registered, partner.approved, tenant.capability-enabled.
0.3	14 Jun 2026	The set gains sub-hierarchies. Onboarding (customer, partner, capability) moves under workflow/onboard/ with an overview manual (SPEC-PWF-ONB); the operating lifecycles (coverage, incident, billing) move under workflow/operate/ with an overview manual (SPEC-PWF-OPS). The central doc-nav (docs-nav.js) gains a generic group model — a family node may now be a group (overview + drill-downs); a group renders inline when active, collapses to a chip otherwise — and the cross-system links move to their own row. No workflow content changed; the renderers became depth-aware so docs resolve from any folder. Candidate next groups logged: identity & access (sign-in + access), sell & channel (quote-to-cash + partner channel).
0.4	14 Jun 2026	The Federation group lands (SPEC-PWF-FED, workflow/federation/): sign-in and access move in, and two new processes split from the access model join them — Defining roles (SPEC-PWF-ROL) and Permission matrix & scope (SPEC-PWF-PRM) — mapped to the Federation PRD's six-layer identity model. Now 12 workflows in 3 groups. Roles owns the role-set definition (FED-6…8), Permissions owns the role×permission matrix + scope (FED-9–10); Access keeps assignment, so the three compose without duplication (WF-8). FED-* ids now route to the Federation PRD in cross-references.
0.5	14 Jun 2026	Field visit joins the Service operations group (SPEC-PWF-FLD, workflow/operate/Field Visit.html) for the new sixth app (SPEC-PRD v0.18, SPEC-APP-FLD). The engineer's on-site execution of a scheduled visit — dispatch → check-in → corrective/preventive work → parts & evidence → customer sign-off → offline sync — composing with Incident and Coverage (WF-8) and audited as RiverSync-in-tenant work (WF-5). Now 13 workflows. Rides visit.checked-in · visit.completed · maintenance.due; traces to FLD-1…9 and DM-27…31.
0.6	15 Jun 2026	Customer-onboarding step wording “site locations” → “sites”, matching the Account app menu rename (entity SiteLocation → OrganizationSite, SPEC-ERD v0.16 / SPEC-APP-ACC v0.5). View-only wording change.
0.7	27 Jun 2026	FK naming convention (SPEC-ERD v0.20) — the derived PartnerLink → PartnerCustomer entity reference in workflow-catalog.js (Users-roles-access and Maintenance-lifecycle workflows); customer/partner FKs read CustomerId · PartnerId. View references only — no step, lane or event change.
0.8	27 Jun 2026	Device classification & schema registration joins as the fourteenth process (SPEC-PWF-DCL, standalone at workflow/): profile the fleet → register schema family/version → catalog the model → resolve each device to its (family, version) at ingest, with needs-review and quarantine branches. Realizes the products taxonomy (SPEC-ERD v0.21, PRO-1…6, DM-35…38) and Initiative 015. Added to the Operate phase of the landscape (and the stale coverage landscape key corrected to agreement); index, matrix and traceability re-render from the catalog.
0.10	28 Jun 2026	Lead to opportunity joins as the fifteenth process (SPEC-PWF-L2O, standalone at pwf/Lead to Opportunity.html) — the CRM front of the funnel: an inbound from one of six sources becomes a Lead off a contact, is qualified (or shared to a partner, tier-gated), converts to an Opportunity that resolves the customer, and a confirmed variant becomes a Deal. Sits before Quote to Cash in Sell & channel; quote-to-cash re-points to begin at a confirmed opportunity. Cascades from master SAL-1…8 / SPEC-ERD DM-43…52 / SPEC-DWF-SAL lifecycles.
0.11	28 Jun 2026	Communications joins as the sixteenth process (SPEC-PWF-COM, standalone at pwf/Communications.html) — the unified inbox: a message on any channel (web form · email · LINE · Instagram · Facebook · LinkedIn · phone) is matched to a contact, threaded into a Conversation, triaged, replied on its own channel and logged as an activity, or filed to junk / archived / deleted (reversible soft states, retained per policy). Sits beside Lead to opportunity in the funnel front; distinct from Support's ChatThread. Cascades from SPEC-PRD SAL-9 / SPEC-APP-PIP PIP-15 / SPEC-ERD DM-53 · DM-54 / SPEC-DWF-SAL (Conversation lifecycle). Index, matrix and traceability re-render from the catalog.
0.12	28 Jun 2026	Forwarding step (SPEC-PWF-COM). The Communications process's reply step becomes Reply or forward on the channel — a reply, a Forward (the conversation) or Forward all (the entire thread, every message) — adding the conversation.forwarded event to the process. Cascades from SPEC-PRD SAL-9 (amended) / SPEC-APP-PIP PIP-15 / SPEC-ERD DM-54.